Home Assistant

Home Assistant 是一个自由开源的智能家居自动化平台。

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ="Asia/Shanghai" \
  -v /mnt/user/appdata/homeassistant:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  homeassistant/home-assistant:2025.3.1

访问主页：http://192.168.110.3:8123。在做反向代理时，需要添加如下配置，否则服务会返回 400：

configuration.yaml

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 111.173.106.175 # Add the IP address of the proxy server
    - 127.0.0.1

配置 MQTT

要启用 SSL 登录，填写 代理地址、端口（SSL 监听端口）、用户名、密码之后，打开【高级选项】。提交之后，就会出现高级选择设置菜单，将【代理证书验证】设置为 自动（我们从 Let’s Encrypt 申请的证书）。【MQTT 协议】默认选择 3.1.1。点击【提交】即可成功连接 MQTT Broker。

接入提要

Integration

• Integration 是 Home Assistant 连接外部设备、服务或平台的模块。
• 它负责和外部系统通信、生成实体、暴露服务，并把状态变化接进自动化体系。
• 真正做设备接入时，先判断是直接复用现成集成，还是自己走 MQTT 这类通用入口。

Entity

• Entity 是 Home Assistant 里最小的逻辑单元。
• 一盏灯、一个传感器、一个按钮，最终都会落成某个实体。
• 设计接入时要先想清状态、属性和能力分别是什么，而不是只想着“页面上显示一个控件”。

Service

• Service 是可调用动作。
• 例如开灯、发唤醒包、更新状态，都属于服务层动作。
• 当需求变成“切换某个控件时，还要联动发消息或执行动作”，本质上就是实体状态和服务调用之间的编排问题。

MQTT 发现与控制

对于自定义设备接入，优先考虑 MQTT。

• 设备端实现成本通常比原生集成更低。
• Home Assistant 页面和自动化可以直接复用现有组件模型。
• 对 DIY 设备来说，维护成本更可控。

Discovery 主题

设备发现常见主题格式：

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• <discovery_prefix> 默认一般是 homeassistant
• <component> 代表组件类型，例如 light、switch、sensor
• <node_id> 可选，主要用于开发者自己做层级区分
• <object_id> 用于唯一标识设备或对象

几个实用判断

• 想在主页显示一个控件并展示状态，先确定对应的实体类型。
• 想通过开关触发多个 MQTT 主题，本质上是状态主题和命令主题的设计问题。
• 想在 turn_off 一类动作时顺带发消息，通常要通过自动化、模板实体或 MQTT 相关集成能力来组合实现，而不是指望单个开关控件天然支持所有副作用。

Home Assistant Community Store

HACS 是一个很重要的插件，更新很及时。Home Assistant 默认自带的插件，基本都用不了。

docker exec -it homeassistant bash
wget -O - https://get.hacs.xyz | bash - # 创建 custom_components 文件夹,然后将 hacs 下载解压至该目录
docker restart homeassistant # 安装任何 custom_components 都重启容器

Xiaomi Miot For HomeAssistant

Xiaomi Miot Auto 提供了接入米家设备的能力。

kiosk-mode

kiosk-mode 可以用来自定义是否显示一些页面组件，例如标题栏。隐藏标题栏后，如果想让标题栏暂时显示，即 kiosk-mode 暂时生效，可以在当前 URL 路径后添加 ?disable_km。